No event has occurred. Also called a “null event.”
The doNothing event indicates that the event queue is empty and that no event has occurred. This occurs only when PollSystem returns with a value of false.
Programming Considerations
``````````````````````````
• Applications that do on-going processing while waiting for events
should do their processing only when a null event is received.
Request to activate an inactive window that belongs to your application.
The request to activate an inactive window is made in response to the user clicking anywhere on an inactive window that belongs to your application. However, there is one exception. If the user clicks in an inactive window’s title bar while holding the Command key, the window is dragged without being activated.
Programming Considerations
``````````````````````````
• A window can be activated by using the ActivateWindow procedure.
• If the active window has an active editing field, you may want to
validate the edited text before allowing the user to activate another
window. If this is the case, use GetFieldString to obtain a copy of
the edited text, then your application can check the string for
errors. If an error is detected, display an appropriate alert box and
ignore the doChgWindow event. If no error is detected, call the
SaveFieldString procedure to save the edited text as the field’s
string, then activate the required window.
• If your application decides not to allow the user to activate a
window, it should display an appropriate alert box to explain why.
• The doChgWindow event will never occur when a modal window is active,
or when the watch cursor is displayed since other windows belonging to
your application cannot be clicked.
• If your application is running under Finder (System 6 or prior), a
doChgWindow event will not occur when the user [1] clicks a desk
accessory from an active window, [2] clicks a desk accessory from
another active desk accessory, or [3] clicks the previously active
window from an active desk accessory. These are all handled
A window’s contents need to be refreshed (redrawn).
Your application must respond to this event. The doRefresh event occurs when a window is completely or partially obscured, then becomes uncovered. Tools Plus takes care of redrawing buttons, scroll bars, editing fields, list boxes, and custom controls. Your application must take care of refreshing anything else, such as icons, pictures, lines, or text that it may have put in the window.
When a doRefresh event is reported, the window’s “update region” will define the exact areas that need to be refreshed. Although you can redraw everything in the window, only the parts of the window that are visible and which need refreshing will actually be redrawn.
Programming Considerations
``````````````````````````
• When your application detects a doRefresh event, it should respond in
the following manner:
CurrentWindow(Poll.Window); {Make the affected window the }
{ current grafPort. }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only within}
{ the area that needs }
{ refreshing (includes all }
{ monitors). }
for theScreen:=1 to NumberOfScreens do {Repeat drawing for each monitor}
begin { in which the window appears. }
BeginUpdateScreen(theScreen); {Drawing area reduced to the }
{ specified screen. }
{ …insert your color-dependent drawing code here… }
EndUpdateScreen; {End the drawing for this }
{ monitor, and restore the }
{ window’s visible (drawing) }
end; { region. }
{ …insert your color-independent drawing code here… }
EndUpdate(WindowPointer(Poll.Window)); {End the update for the window }
CurrentWindowReset; {Reset the current window to be }
{ the same as the active window}
{ (optional command). }
• If your application did not put anything in the window except buttons,
scroll bars, editing fields, list boxes, and custom controls, all it
needs is the BeginUpdate and EndUpdate routines. Note that
BeginUpdate and EndUpdate cannot be nested.
• It is possible that several windows will need to be refreshed
simultaneously if, for instance, a closing window exposed three
windows behind it. PollSystem reports a single doRefresh event each
time it is called in the event loop, one event for each window that
needs refreshing.
• Unlike traditional Pascal, a doRefresh event is not generated when a
window is first opened.
• A doRefresh event is not generated for desk accessories, dialogs,
alerts, or Dynamic Alerts. These events are handled automatically.
The request to close the active window is made in response to the user clicking inside the window’s “close” box. This has the same effect as choosing the File menu’s Close item.
Programming Considerations
``````````````````````````
• A window is closed by using the WindowClose procedure.
• If the window has an active editing field, you may want to validate
its edited text before allowing the user to close the window. If this
is the case, use GetFieldString to obtain a copy of the edited text,
then your application can check the string for errors. If an error is
detected, display an appropriate alert box and ignore the doGoAway
event. If no error is detected, call the SaveFieldString procedure to
save the edited text as the field’s string, then close the required
window.
• If any changes have been made in the window’s data, your application
should display an appropriate alert box and ask the user if changes
should be saved. The options should be Yes, No, and Cancel, the last
of which would ignore the doGoAway event.
• If a modal window has a “close” box and the operator types Command-W,
a doGoAway event is generated for that window.
• The doGoAway event will never occur when the watch cursor is
displayed, since the close box cannot be clicked.
• A doGoAway event is not generated when the user clicks a desk
accessory’s close box. The desk accessory is closed automatically.
The doButton event reports that the user has clicked a button in the active window. This includes push buttons, check boxes and radio buttons. The doButton event is also reported if the active window has a default push-button, and the user pressed the Return or Enter key to invoke the default. If this is the case, the window’s default button will already have been “flashed” as if the user had clicked it.
Programming Considerations
``````````````````````````
• If the user clicked a check box, use SelectButton to reverse the check
box’s selection (i.e. select or deselect it).
• If the user clicked a radio button, use SelectButton to select the
radio button, and to deselect the other buttons in the radio button’s
group.
• This event will never occur when the watch cursor is displayed, since
buttons cannot be clicked. The exception is if the WatchCursorButtons
procedure has been used to allow the watch cursor to click push-
buttons.
• If your application responds to double-clicks in radio buttons and
Poll.Button.DoubleClick is true, consider the event to mean “click
button and OK,” in which case the default button should be flashed and
the appropriate action taken.
• A doButton event is not generated when the user clicks buttons in a
dialog box, alert box, or desk accessory. These events are handled
Indicator that the user held down a key, and it is repeating.
The user has pressed down a key on the keyboard or numeric pad, and the key is repeating. The key cannot be processed internally by Tools Plus. In most cases, this event should be treated identically to a doKeyDown event. Each doAutoKey event will follow a doKeyDown of the same sort, so your application may want to make some repeating Command key sequences illegal.
Programming Considerations
``````````````````````````
• This event is generated only if the key can not be processed
internally by Tools Plus.
• Command key sequences that are equivalents to menu items generate
doMenu events.
• The Modifiers field tells your application if the repeating key down
event was a Command key sequence. All Command key sequences that are
not menu equivalents are returned to your application as doKeyDown or
doAutoKey events. If your application gets such a Command key
sequence, it should carry out the appropriate action, or beep the user
if the Command key sequence is illegal.
• If Return or Enter are typed and held down when the active window has
a default button, a doButton event is reported for the default button.
• If an active editing field exists on the active window, repeating keys
will affect the field and will not generate events. This applies even
if the field’s length is limited, or if Return has been disallowed in
a field.
• If Tab is typed and the window contains an active editing field, it
indicates that the user wants to tab to the next field. Shift-Tab
indicates tabbing to the previous field. You may want to validate a
field’s edited text before allowing the user to tab to the new field.
If this is the case, use GetFieldString to obtain a copy of the
edited text, then your application can check the string for errors.
If an error is detected, display an appropriate alert box and ignore
the doKeyDown event. If no error is detected, call the
SaveFieldString procedure to save the edited text as the field’s
string, then activate the new field by using the ActivateField
procedure.
• If Return is typed and the window contains an active editing field,
it usually indicates that the user wants to tab to the next field.
See “Tab” above. A Return key is reported only if the window does not
have a default button.
• If Enter is typed, it usually indicates that the user wants to enter
the screen’s data. This is the same process that is carried out by
clicking an OK button. See “Tab” above, regarding validating and
saving a field’s edited text. An Enter key is reported only if the
window does not have a default button. The repeating Enter key may be
considered illegal because a doKeyDown event will report the first
Enter, after which your application should have acted accordingly. An
Enter key will be reported only if the window does not have a default
button.
• When the watch cursor is displayed, the only doAutoKey event that will
be reported is a Command-., which is the user’s request to halt a
lengthy process. Other doAutoKey events are discarded.
• If the active window has an active editing field, PollSystem
automatically processes the Command key equivalents for the Edit
menu’s Undo, Cut, Copy, and Paste commands. These selections do not
generate events.
• There are two situations where several keys produce the same key
character: the Clear and Escape keys, and the F1 through F15 keys. In
these cases, use the key code to differentiate the keys. Constants
are provided for these key characters and key codes.
• A doAutoKey event is not generated when the user types in a desk
accessory. These key strokes are handled automatically.
The user has released a key on the keyboard or numeric pad, and the key cannot be processed internally by Tools Plus. Normally the Macintosh does not report doKeyUp events nor do applications typically respond to them. See “Key-Up Events” in the Designing Your Application chapter for details on the SetEventMask procedure.
Programming Considerations
``````````````````````````
• This event is generated only if your application has used the
SetEventMask procedure to make the Macintosh respond to key-up events,
and if the active window does not have an active editing field.
• Tools Plus and desk accessories do not require key-up events, and
therefore ignore them.
• There are two situations where several keys produce the same key
character: the Clear and Escape keys, and the F1 through F15 keys. In
these cases, use the key code to differentiate the keys. Constants
are provided for these key characters and key codes.
• When the watch cursor is displayed, all doKeyUp events are discarded
Indicator that the user clicked in an inactive editing field.
When the user clicks in an inactive editing field in the active window, it indicates that the user has finished working with the currently active field and wants to start working with the one that was clicked. Tools Plus automatically supports the full range of Macintosh user-interface options for editing fields, including (but not limited to):
• clicking in the field, thereby placing an insertion point
• dragging across characters to create a selection
• double-clicking a word to select it
Programming Considerations
``````````````````````````
• The ClickInField procedure is used to process a user’s click in an
inactive editing field.
• If an editing field is active when you receive a doClickField event,
you may want to validate its edited text before allowing the user to
click to the new field. If this is the case, use GetFieldString to
obtain a copy of the edited text, then your application can check the
string for errors. If an error is detected, display an appropriate
alert box and ignore the doClickField event. If no error is detected,
call the SaveFieldString procedure to save the edited text as the
field’s string, then call the ClickInField procedure to process the
user’s click in the new field.
• Between the time that the doClickField event is reported and the
ClickInField procedure is used as a response, observe the following
rules:
• do not call PollSystem
• do not open or close any windows
• do not activate an inactive window
• do not use alerts or dialogs.
If these rules are not observed, ClickInField will do nothing and the
user’s click will be ignored.
• An event will not occur if the user clicks in an editing field that is
already active.
• This event will never occur when the watch cursor is displayed, since
editing fields cannot be clicked.
• A doClickField event is not generated when the user clicks in a desk
accessory’s editing fields. The process is handled automatically.
The doScrollBar event reports that the user has clicked somewhere in a scroll bar. The scroll bar has 5 parts: up button, down button, “page up” region, “page down” region, and the thumb. In all cases, your application should respond to the scroll bar event by scrolling the window’s contents (or portion thereof) and drawing any parts that have been newly revealed due to scrolling.
Programming Considerations
``````````````````````````
• If the scroll bar’s thumb was moved, your application can obtain the
current value of the scroll bar by calling GetScrollBarVal. By using
this value, your application can determine how much to scroll.
• If the scroll bar’s up button, down button, “page up” region, or “page
down” region was clicked, your application must scroll the window by
the correct amount, then change the scroll bar’s value by using
SetScrollBarVal.
• If the up arrow or “page up” region is clicked, subtract the correct
amount from the current value. If the down arrow or “page down”
region is clicked, add the correct amount to the current value.
• If the user holds the mouse button down in the up arrow, “page up”
region, down arrow, or “page down” region, PollSystem returns a single
doScrollBar event each time PollSystem is called. Your application
doesn’t have to be aware of this, but it is nice to know that scroll
bar events will not pile up in the queue.
• If the user moves the scroll bar’s thumb and returns it to its
original place during the same drag, an event is not generated.
• This event will never occur when the watch cursor is displayed, since
scroll bars cannot be clicked.
• Scroll bars that are part of a list box are handled automatically.
• A doScrollBar event is not generated when the user clicks scroll bars
in a dialog box or desk accessory. These events are handled
Indicator that user clicked or double-clicked in a list box.
The doListBox event reports that the user has clicked somewhere in a list box (on a line that contains text or a blank line). This event is not generated when the user just scrolls the list box by using its scroll bar.
Programming Considerations
``````````````````````````
• If your application treats double-clicks in list boxes like clicking
the OK button, use the GetListBoxLine function to determine which line
was selected (or GetListBoxLines if multiple lines can be selected in
the list box), then flash the OK button with the FlashButton
procedure.
• This event will never occur when the watch cursor is displayed, since
list boxes cannot be clicked.
• A doListBox event is not generated when the user clicks list boxes in
a dialog box or desk accessory. These events are handled
Indicator that the user has completed or in the midst of a click, double-click, triple-click, or drag.
A click, double-click, triple-click, or drag has been reported in the active window. The event may still be in progress when PollSystem reports it, such as a double-click with the mouse button still down on the second click. The Mouse part of the event record contains a field called What, which is the mouse event code that tells your application what type of mouse click has occurred. The rest of the mouse record contains details on each mouse-down and mouse-up event.
A series of decisions are made by PollSystem to obtain single and multiple-click information, as well as drags. Although they can be somewhat altered by your application (as explained later), the steps taken are as follows:
1 The first mouse-down of a click will be in the active window’s
content region, and will not be in a button, a scroll bar, an
editing field, a list box, or a custom control.
2 If no mouse-up event is in the queue, a “single-click, mouse still
down” mouse event code is returned. If a mouse-up event is in the
queue, it is used to complete the click.
3 If the time between the first mouse-down and the first mouse-up
(single-click) was too long to be the first click of a multiple
click, PollSystem returns with a “single-click completed” mouse
event code.
4 If the time between the first mouse-down and the first mouse-up
(single-click) was short enough to constitute the first click of a
multiple click, PollSystem checks the event queue for a mouse-down
event that would be the beginning of a second click. If a mouse-
down event is not found in time, PollSystem returns with a “single-
click completed” mouse event code.
5 If a second mouse-down event is in the queue, it must be in the
active window’s content region, and must not be in a button, a
scroll bar, an editing field, a list box, or a custom control. If
any of these conditions are violated, the mouse-down event is left
in the queue and PollSystem returns with a “single-click completed”
mouse event code. If the conditions are not violated, PollSystem
continues.
6 The second click has begun. If no mouse-up event is in the queue, a
“double-click, mouse still down” mouse event code is returned. If a
mouse-up event is in the queue, it is used to complete the click.
7 If the time between the second mouse-down and the second mouse-up
(double-click) was too long to be the second click of a triple-
click, PollSystem returns with a “double-click completed” mouse
event code.
8 If the time between the second mouse-down and the second mouse-up
(double-click) was short enough to constitute the second click of a
triple-click, PollSystem checks the event queue for a mouse-down
event that would be the beginning of a third click. If a mouse-down
event is not found in time, PollSystem returns with a “double-click
completed” mouse event code.
9 If a third mouse-down event is in the queue, it must be in the
active window’s content region, and must not be in a button, a
scroll bar, an editing field, a list box, or a custom control. If
any of these conditions are violated, the mouse-down event is left
in the queue and PollSystem returns with a “double-click completed”
mouse event code. If the conditions are not violated, PollSystem
continues.
10 The third click has begun. If no mouse-up event is in the queue, a
“triple-click, mouse still down” mouse event code is returned. If a
mouse-up event is in the queue, it is used to complete the click and
return a “triple-click completed” mouse event code.
Programming Considerations
``````````````````````````
• If at some point your application is only concerned with a mouse down
in a certain area, or a single-click only, or a double-click only, you
can disrupt the click as soon as you have obtained enough information
by using ResetMouseClicks. For example, if your application only
cares about a single-click and it gets a “double-click, mouse still
down” mouse event code, ResetMouseClicks will tell PollSystem “forget
the rest of this click.”
• A triple-click should be scrutinized by your application because the
time between the third mouse-down and the third mouse-up may be longer
than the allowable limit for consecutive clicks. This will also
happen when the user double-clicks, then presses down the mouse button
the third time and drags. Use the GetDblTime function to determine
the maximum number of clock ticks which can occur between mouse-down
and up events to constitute a consecutive click.
• Your application can place cursor zones on a window, then use
FindCursorZone to determine if a click occurred in one of those zones.
This can make parts of your window, such as pictures or icons, click-
sensitive. See “Cursors” for information about Cursor Tables and
Cursor Zones.
• This event will never occur when the watch cursor is displayed, since
only buttons can be (optionally) clicked.
• A doClick event is not generated when the user clicks in a desk
accessory’s editing fields. The process is handled automatically.
Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Mouse.What
Poll.Mouse.Down[1].Where
Poll.Mouse.Down[1].When
Poll.Mouse.Down[1].Modifiers
The next three fields are valid only if the mouse event code is inClick1, inClick2Drag, inClick2, inClick3Drag, or inClick3.
Poll.Mouse.Up[1].Where
Poll.Mouse.Up[1].When
Poll.Mouse.Up[1].Modifiers
The next three fields are valid only if the mouse event code is inClick2Drag, inClick2, inClick3Drag, or inClick3.
Poll.Mouse.Down[2].Where
Poll.Mouse.Down[2].When
Poll.Mouse.Down[2].Modifiers
The next three fields are valid only if the mouse event code is inClick2, inClick3Drag, or inClick3.
Poll.Mouse.Up[2].Where
Poll.Mouse.Up[2].When
Poll.Mouse.Up[2].Modifiers
The next three fields are valid only if the mouse event code is inClick3Drag, or inClick3.
Poll.Mouse.Down[3].Where
Poll.Mouse.Down[3].When
Poll.Mouse.Down[3].Modifiers
The next three fields are valid only if the mouse event code is inClick3.
Poll.Mouse.Up[3].Where
Poll.Mouse.Up[3].When
Poll.Mouse.Up[3].Modifiers
Poll.Mouse.Where
CONST {Mouse Event Codes }
inClick1 = 1; {single-click completed }
inClick2 = 2; {double-click completed }
inClick3 = 3; {triple-click completed }
inClick1Drag=-1; {single-click, mouse still down }
inClick2Drag=-2; {double-click, mouse still down }
